1 CREATING AND RUNNING PROGRAMS 
There are 3 stages to producing a program using OPL, the Psion programming 
language: 

e Type in the program, using the Program editor. 


e Translate the program. This makes a new version of your program in a format 
which can “run”. 


@ Run the program. If it does not work as you had intended, re-edit it, then translate 
and run it again. 


This chapter guides you through these stages with a simple example. If you wish to 
follow the example, note that each instruction for you to do something is numbered. 


aN The example programs in the first few chapters do not include full error handling. This keeps the 
programs short and easy to understand, but it means that when you run one of these programs and, 
for example, fail to type in the kind of value which the program asks for, the program may fail 
harmlessly stopping before it completed. As you develop your own programs, you slioulds usually 
add some error handling code to on A later chapter gives a full explanation of error handling. 
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CREATING A NEW MODULE 


As well as the word program, you'll often see the word module used. The terms program and module 
are used almost interchangeably to describe each OPL file - you say “OPL module” like you might say 
“Word Processor document”. 


Create a new module and give it a name: 


I 1. Click the ‘New File’ button (or select ‘Create New File’ from the ‘File’ menu). 


2. Select ‘Program’ from the ‘Program’ selector. 


3. Type test as the ‘Name’ to use for this OPL module and press Enter. You will move into the 
Program editor. 


Module names can be up to 256 characters long (including their folder names), like other file 
names on the Series 5. The names may include any characters except \, / and :, and any trailing 
spaces or dots (.) will be stripped automatically. 
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1. Move to the Program icon on the System screen, and select ‘New file’ from the ‘File’ menu. 


2. Type test as the name to use for this OPL module and press Enter. You will move into the 
Program editor. 


Module names can be up to 8 characters long, like other filenames on the Series 3c. The names 
can include numbers, but must start with a letter. 


It’s always best to choose a name that describes what the module does. Then, when you’ve written 


several modules, you can still recognise which 1s which. 


Inside the Program editor 


When you first move into the Program editor you will see that PROC : has already been entered on the 
first line, and ENDP on the third. 


PROC and ENDP are the keywords that are used to mark the start and end of a procedure. Larger 
modules are broken up into procedures, each of which has one specific function to perform. A simple 
OPL module, like the one you are going to create, consists of only one procedure. 


A procedure consists of a number of statements — instructions upon which the Psion acts. You type 
these statements, in order, between PROC : and ENDP. When you come to run the program, the Psion 
goes through the statements one by one. When the last statement in the procedure has been completed 
and ENDP 1s reached, the procedure ends. 


You can type and edit in the Program editor in much the same way as in the Word application, except 
that text you type does not word-wrap; you should press Enter at the end of each statement. Note also 
that on the Series 3c, the Program editor does not offer text layout features such as styles and 
emphases. 


~ You can use upper or lower case letters when entering OPL keywords. 


AN EXAMPLE PROCEDURE TO TYPE IN 


The next few pages work with this example procedure: 
PROC. Cesc: 
PRIN? “This 1S my °OPL program” 
PAUSE 80 
Clio 
PRINT “Press a key to finish” 


GET 


ENDP 


This procedure does nothing of any real use it is just an example of how some common OPL keywords 
(PRINT, PAUSE, CLS and GET) are used. The procedure first displays This is my OPL 
program on the screen. After a few seconds the screen is cleared and then Press a key to 
finish 1s displayed. Then, when you press a key, the program finishes. 


TYPE IN AND EDIT THE PROCEDURE 


Before you type the statements that constitute the procedure, you must type a name for it, after the 
word PROC. The flashing cursor is automatically in the correct place for you to do this (before the 
colon). You can choose any name you like within the following restrictions: 


I Procedure names may have up to 32 characters. The alphabetic and numeric characters are 


allowed and also the underscore character, . The first character of any procedure name must be 
either an underscore or an alphabetic character. 
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Procedure names may have up to 8 characters. The alphabetic and numeric characters are allowed 
only. The first character of any procedure name must be an alphabetic character. 


For simple procedures which are the only procedure in a module, you might use the same filename you 
gave the module. 


1. Type test . The top line should now read PROC test: . 
2. Press 6. The cursor is already indented, as if the Tab key had been pressed. 
You can now type the statements in this procedure: 


3. Type PRINT “This is my OPL program”. (Note the space after PRINT.) Press Enter at the 
end of the line. 


Each new line is automatically indented, so you don’t need to press the Tab key each time. These 
indents are not obligatory, though as you’ll see, they can make a procedure easier to read. However, 
other spacing, such as the space between PAUSE and 80, is essential for the procedure to work 


properly. 


4. Type the other statements in the procedure. Press Enter at the end of each line. You are now ready 
to translate the module and then run it. 


When you are entering the statements in a procedure you can, if you want, combine adjacent lines by 
separating them with a space and colon. For example, the two lines: 


PAUSE 80 

Cis 

could be combined as this one line: 
PAUSE GO: 2CLsS 


You can, of course, use the other Psion applications at any time while you are editing an OPL module. 


I Toreturn to editing your program, either 


e@ tap on the Program icon on the Extras bar, or 
e select the module’s name on the System screen, or 


e use the Task List to return to the Program editor. 


X\ 


I Use Control-Word (hold down the Control key and press the Word button) to return to the 
Program editor to continue editing your program. 
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What the keywords do when the program runs 


PRINT - takes text you enter between quote marks, and displays it on the screen. The text to be 
displayed, in the first statement, is This is my OPL program. 


PAUSE - pauses the program, for a specified number of twentieths of a second. PAUSE 80 waits for 4 
seconds. (PAUSE 20 would wait for 1 second, and so on.) 


CLS - clears the screen. 


GET - waits for you to press a key on the keyboard. 


TRANSLATING A MODULE 
The translation process makes a separate version of your program 1n a format which the Psion can run. 
You’d usually try to translate a module as soon as you finish typing it in, to check for any typing 


mistakes you’ve made, and then to see if the program runs as you intended. 


I 1. Select the ‘Translate’ option from the ‘Tools’ menu or tap the ‘Tran’ button on the toolbar 
menu. 
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1. Select the ‘Translate’ option from the ‘Prog’ menu. 


The Series 3c ‘Prog’ menu also has a ‘S3 translate’ option, for translating the current program in 
a form which can run on a Series 3 (as opposed to a Series 3c). 


What happens when you translate a module? 

First: the procedures in the module are checked for errors 

If the Psion cannot understand a procedure, because of a typing error, a message is shown, such as 
‘Syntax error’. The cursor is positioned at the point where the error was detected, so that you can 


correct it. For example, you might have typed PRONT “This is...”,or PAUSE80 without the 
space. 


When you think you’ve corrected the mistake, select ‘Translate’ again. If there is still a mistake, you 
are again taken back to where it was detected. 


A If you’ve already used up almost all of the memory, the Psion may be unable to translate the 
program, and will report a ‘No system memory’ message. You’ll need to free some memory before 
trying again. 


When ‘Translate’ can find no more errors, the translation will succeed, producing a separate 
version of your module in a format which the Psion can run. 


There may still be errors in your program at this point because there are some errors which cannot be 
detected until you try to run the program. 


Running after translating 
When your module translates successfully, the ‘Run program’ dialog is displayed, asking whether to 
run the translated module. You’d usually run it straight away in order to test it. 


A Running a module does require some free memory, so again a “No system memory’ message is 
possible. 


1. Press ‘Y’ to run the module; the screen is cleared, and the module runs. 


When the module has finished running, you return to the Program editor, with the cursor where it was 
before. 


If an error occurs while the module is running, you will return to editing the module, and the cursor 
will be positioned at the point where the error occurred. 


FILE MANAGEMENT 


New OPL modules 


You can create new OPL modules in the same way as new Word documents. 


I 
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Either create it from the Program editor using the ‘Create New file’ option in ‘File’ menu, or from 


the System screen by clicking on the ‘New File’ button (or select ‘Create New File’ from the 
‘File’ menu). 


The module names are listed on the System screen with a Program icon next to them. The 
Program icon looks like a sheet of paper with “OPL” on it. Successfully translated modules will 
also be listed in the same folder as their corresponding Program file with the OPL icon next to 
them. The OPL icon 1s just the letters “OPL” with a shadow. 


To re-edit an existing OPL program, you can open the Program application and use the “Open 
file’ option from the ‘File’ menu. You could also select the file directly from the System screen. 
This will automatically open the file and launch the Program application. Files which launch 
their associated applications when selected are known as documents. The application U/D 
(unique identifier) is stored in the document header which 1s read by the system. As far as the 
user 1s concerned, the UID specifies a document’s type. A non-document file does not have an 
application UID and is displayed on the system screen with a special icon (a question mark) 
showing that it is unrecognised. Non-document files are known as external files. 


Opening Program from its icon in the Extras bar will re-open the Program file last in use. 


Either create it from the Program editor using the ‘New file’ option in ‘File’ menu, or from the 
System screen by moving to the Program icon and using its ‘New File’ option. 
Your module names are listed below the Program icon. The Program icon is a speech bubble 


containing “OPL” on a grey background. The word ‘Program’ is shown below the icon if there 
are no modules at all. 


The names under the RunOpl icon are those modules which have been translated successfully. 
The RunOpl icon is just “OPL” in a speech bubble. 


To re-edit an existing OPL program, use the ‘Open file’ option in the Program editor, or move to 
the Program icon in the System screen and select the filename from the list. 


Copying modules 


Use the ‘Copy file’ option in the System screen to copy modules (or translated modules). See the User 


Guide for full details. You can also use the ‘Save as’ option in the Program editor itself, to make new 
copies of an OPL module. 


Deleting modules 


You can delete an OPL module (or a translated version) as you would any other file. Go to the System 


screen, move the highlight on to the file and use the ‘Delete file’ option. 
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If you delete all of your translated modules, the RunOpl icon will remain on the System screen, 
with the word RunOpl beneath it. 


‘File is in use’ 


If you see a “File’ is 1n use’ (‘File or device in use’ on the Series 3c) error message when deleting or 
copying an OPL module, the file is open — it is currently being edited in the Program editor. Exit the 
file and then try again. 


If it’s the translated file you’re trying to delete or copy, “‘File’ is in use’ (‘File or device in use’ on the 
Series 3c) means that the translated file is currently running. Stop the running program by going to the 


running program, then either wait for the program to complete or press Ctrl+Esc (on the Series 5; 
Psion+Esc on the Series 3c) to stop it, and then you can try again. 
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MorE ABOUT RUNNING MODULES 


Running from the Program editor 


You can run a module at any time from within the Program editor, by selecting “Run program’ (‘Run’ 
on the Series 3c) from the ‘Tools’ menu (‘Prog’ menu on the Series 3c). This runs the translated 
version of your program; if you’ve made changes to the module and haven’t translated it again, you 
must translate the module again, or the changes have no effect. 


‘Run program’ (‘Run’ on the Series 3c) displays a dialog, letting you select the name of any translated 
module which you want to run. 


Running modules from the System screen 


The names of any successfully translated programs automatically appear in the System screen. 


I Translated modules appear in the System screen with the OPL icon to the left of them. They have 
the same name as the Program file from which they were translated with the extension . OPO 
added to their name, and appear in the same folder as their corresponding Program file. Just move 
the highlight on to the name of the translated program you want to run, and select it. 
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Translated modules appear underneath the RunOpl icon. This appears at the right-hand end of the 


list of icons (past the Program icon), and is usually off the right-hand edge of the screen. Just 
move the highlight on to the name of the translated program you want to run, and press Enter. 


Like the Program editor, RunOpl is assigned a keypress - you can press Control-Calc (hold down 
Control and press the Calc button) as the short-cut to move to the RunOpl icon, whatever you’re 
doing. (If there is a running program, this instead moves directly to it.) 


When an OPL module has been successfully translated and run, you will usually run it from the System 
screen. While you’re still editing and testing, however, it’s quicker to run it from inside the Program 
editor. This also positions the cursor for you, if errors occur. 


Stopping a program while it’s running 

I To stop a running program, press Ctrl+Esc. (If you’ve gone away from the running program it 
will still be running, and you must first return to it. This 1s done by either selecting it from the 
System screen or by using the Task list to switch to it. Then Ctrl+Esc will stop it.) 


To pause a running program, press Ctrl+Fn+S. It will be paused as soon as it next tries to 
display something on the screen. Press Ctrl+Fn+Q to let the program resume running. 
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To stop a running program, press Psion+Esc. (If you’ve gone away from the running program 


it will still be running, and you must first return to it. This is done by pressing Control-Calc 
and/or selecting it from under the RunOpl icon in the System screen before pressing Psion-Esc.) 


To pause a running program, press Control-S. It will be paused as soon as it next tries to 
display something on the screen. Press any other key to let the program resume running. 


Displaying a status window 


I The Series 5 does not have status windows: it has a toolbar instead. You should see the ‘Friendlier 
Interaction’ chapter for details of this. 


I aA temporary status window is always available while an OPL program is running. Press 
Psion-Menu to see it. As you’ll see, there are keywords for displaying a status window yourself. 


Looking at a running program 


A 


I 
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If you translate and run a module from the Program editor, the Task list will still allow you to 


return to the Program editor, even if the translated program has not finished running. A 
‘Running...’ message 1s shown — you can move the cursor around the program as normal, but 
you can’t edit it. 


To return to the running version, either use the Task list or select 1t from the System screen. It will 
be in bold, to show that it 1s currently running. 


If you translate and run a module from the Program editor, the Control-Word keypress will still 
return to the Program editor, even if the translated program has not finished running. A ‘Busy’ 
message is shown — you can move the cursor around the program as normal, but you can’t edit 
it. 

To return to the running version, select it from beneath the RunOpl icon in the System screen. It 


will be in bold, at the top of the list, to show that it is currently running. Alternatively, press 
Control-Calc to return to it. 


Running more than one module 


If a module is running, and you select a second one from the System screen, the first one is not 
replaced — both modules run together, and will be displayed in bold on the System screen. On the 
Series 5, you can swap between them using the Task list, on the Series 3c use Control-Shift-Calc. 


MENU OPTIONS WHILE EDITING 


While you’re typing in the procedure, all the options on the ‘Edit’ menu such as ‘Copy’ (‘Copy text’ on 
the Series 3c) and ‘Paste’ (‘Insert text’ on the Series 3c) - are available and can be used as in Word. 
Refer to the User Guide for more information. 


I 


The menu options available are in general similar to those found in other applications, such as 


Word. The ‘Tools’ menu has options for translating and running the current program. It also has a 
‘Show last error’ option, to re-display an error which prevented successful translation, and a 
‘Preferences’ option to determine the fonts available and whether spaces, tabs and paragraph ends 
are shown in the Program editor. It also provides an ‘Infrared’ option (see the User Guide for 
more details of using infrared). The ‘Create standard files’ option creates files in RAM from 
ROM files: see the ‘Calling Procedures’ chapter for more details of this. 


The ‘Format’ menu provides an ‘Font’ dialog for changing fonts and styles in the Program editor. 
The ‘Indentation’ option can be used to set the tab width and to turn auto-indentation on and off. 


The ‘File’ menu also include ‘Import text’ and ‘Export as text’ options for importing text and 
exporting as text. These can be used to convert Program files from Series 3a, 3c and Siena to 
Series 5 and vice versa. To convert from earlier Program files to Series 5 Program files you need 
to: 


1. Create a new Program document. 
2. Import the text using the ‘Import text’ option from the ‘More’ cascade in the ‘File’ menu. 


3. Translate and run as usual. 


A Note that there maybe some incompatibility between Series 5 OPL and earlier versions. See 
Appendix A for a summary of these and other chapters as appropriate for further details. 


The toolbar on the left-hand side of the screen provides easy access via buttons to four options 
and also a clock. The options are ‘Tran’ (‘Translate’), ‘Find’, ‘Find next’ and ‘Go to’. These 
options are all self-explanatory, except perhaps for the last: ‘Go to’ gives a list (scrolled if 
necessary) of all the procedure in the module. Selecting one of them jumps to the beginning of the 
specified procedure. 
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The menus available are the same as in the Word application, except that the ‘Word’ menu has 


been replaced by the ‘Prog’ menu. The ‘Prog’ menu has options for translating and running the 
current program. It also has a ‘Show error’ option, to re-display an error which prevented 
successful translation, and an ‘Indentation’ option, for setting the tab width and to turn 
auto-indentation on and off in the Program editor. 


Unlike Word, the Program editor only ever uses one template for creating new files, called 
‘default’. When you use the ‘New file’ option, the ‘Use template’ line is therefore unavailable; 
the new file 1s created using the ‘default’ template automatically. If you wish to change the 
‘default’ template, you can use the ‘Save as template’ option to replace it with the current file. Do 
not try to swap templates between Word and the Program editor. ‘Set preferences’ allows 
you to choose between bold/normal and mono-spaced/proportional text. It also has options for 
showing tabs, spaces, paragraph ends, soft hyphens and forced line breaks. 


There is no ‘Password’ option. 


I The [+] (diamond) key 


The (+) key allows you to switch between a ‘Normal’ and an ‘Outline’ view of your OPL module. The 
‘Outline’ view lists only the names of each procedure, for quick navigation around the module. 


SUMMARY 


A 


I 
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Tap the ‘New file’ button on the system screen and select ‘Program’ as the ‘Program’. 


Type in your procedure. 
Select ‘Translate’ from the ‘Tools’ menu. 


When a module translates correctly you are given the option to run it. You can run it again at any 
time, either with ‘Run program’ in the ‘Tools’ menu, or directly from the System screen. 


Use Ctrl+Esc to stop a running program. 


Use Ctrl+Fn+S to pause a program and Ctrl+Fn-+Q to restart it again. 


Move to the Program icon in the System screen and select the ‘New file’ option. 


Type in your procedure. 
Select ‘Translate’ from the ‘Prog’ menu. 


When a module translates correctly you are given the option to run it. You can run it again at any 
time, either with ‘Run’ in the ‘Prog’ menu, or directly from the RunOpl icon in the System 
screen. 


Use Psion-Esc to stop a running program. 
Use Control-S to pause a program and any other key to restart it. 


Use Psion-Menu to display a status window. 


